ParcelAddress API
Domestic Suburbs Suggestion
Resource URL
UAT:
http://api.uat.nzpost.co.nz/parceladdress/2.0/domestic/suburbs
Production:
https://api.nzpost.co.nz/parceladdress/2.0/domestic/suburbs
Resource Description
Returns a list of suggested domestic suburbs for a suburb fragment.
Resource Information
Attribute | Detail |
---|---|
Response Format | JSON |
Requires Authentication | Yes |
Rate Limited | 15 calls per second. If rate limit is exceeded, calls will be queued. Calls unprocessed for over 60 seconds will time out. |
Please note that all request parameters should be in lower case.
Request Parameters
Field Name | Description | Mand | Example |
---|---|---|---|
count | The number of matching suburbs to be returned. Note that the maximum value for the parameter is 10. | No | 10 |
q | Suburb fragment to search for suggestions. Valid input characters for this parameter include alphanumeric characters. All other characters will be ignored. | Yes | Bays |
Sample Request
https://api.nzpost.co.nz/parceladdress/2.0/domestic/suburbs?q=Bays&count=10
Business Rules
The following business rules are applied on each /suburbs request:
Name | Description |
---|---|
BR001 | The suburb fragment (parameter โqโ) must contain at least 4 characters after the leading and following spaces are removed by the API code. If less than 4 characters, an error message will be returned to the requester. |
BR002 | If no count value is provided, a default number of responses is returned. The default is set to 10 records. |
BR003 | If the count value provided is greater than 10 and there are more than 10 suburbs matching the suburb fragment, only 10 suburb records will be returned to the merchant. |
Response Parameters
The following lists the required fields in the /suburbs response message.
Field Name | Description | Mand | Example |
---|---|---|---|
success | Returns if request is successful | Yes | True |
suburbs | Contains array of suburb detail objects. The number of object will not exceed the โcountโ value defined. | Y if success = true | "suburbs": [] |
message_id | Unique ID for the API call | Y | 94f44cdd-49af-4f60-b023-7a35b9d8c716 |
Suburbs Object
The following lists the fields in the suburb object.
Field Name | Description | Mand | Example |
---|---|---|---|
suburb_details | A text string containing the suburb name followed by town or city and postcode, comma-separated. | Yes | "Bayswater, Otautau, 9682" |
Error Response Elements
Field Name | Description | Mand | Example |
---|---|---|---|
success | Returns if request is successful | Yes | false |
errors | Error object with error details | Y if success =false | See Error Object Parameters below |
message_id | The unique message identifier | Yes | ec608f40-2a8b-11e5-a9c0-025c481d35ef |
Error Object Parameters
Field Name | Description | Example |
---|---|---|
code | Error code where first 3 digits are http status code, last three digits identify error type | 400002 |
message | Description of error code | Invalid Parameter(s) |
details | Description of specific error | Address prefix must be at least 4 characters, not including spaces at the beginning or end. |
HTTP Status Codes
Note that some error messages are customised for the request, i.e. error code 400 usually will describe what is wrong with the request
Code | Message |
---|---|
200 | Success |
400 | Bad request |
401 | Unauthorized |
403 | Forbidden |
409 | Invalid request |
500 | System unavailable |
Error Codes
Code | Message |
---|---|
200001 | Partial results returned, not all system(s) have responded |
200002 | All sources responded, data may be incomplete |
400001 | Parameter(s) missing |
400002 | Invalid parameter(s) |
400003 | Non mutually exclusive parameters detected |
401001 | Unauthorised access, please contact administrator |
500001 | General Exception |
500002 | System(s) offline |
Sample Response
Success Sample:
{
"success": true,
"suburbs": [
{
"suburb_details": "Bayswater, Otautau, 9682"
},
{
"suburb_details": "Bayswater, Otautau, 9683"
},
{
"suburb_details": "Bayswater, Otautau, 9689"
}
],
"message_id": "e86f19ee-a818-4945-9467-abd558dbb083"
}
Failure Sample:
{
"success": false,
"errors": [
{
"code": "400002",
"message": "Invalid parameter(s)",
"details": "Address prefix must be at least 4 characters, not including spaces at the beginning or end."
}
],
"message_id": "6f532fc4-7bee-4cb5-8e39-30791cfcf165"
}